home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / edit / me_cd.zip / MUTT.DOC < prev    next >
Lisp/Scheme  |  1988-10-24  |  25KB  |  640 lines
  1. ========================================================================
  2. ==        The Mutt Programming Language       Craig Durland 9/88 ==
  3. ========================================================================
  4.  
  5. symbol    action
  6.   (    evaluate expression
  7.   )    end expression
  8.   {    start pgm
  9.   }    end pgm
  10.  
  11. SYNTAX
  12. pgm : {exp [exp ...]}, {}
  13. exp : (fcn [args]), (var [args]), var, const, ()
  14. const : number (123, 0xAbC), string ("abc", 'abc'), TRUE, FALSE
  15. arg : block
  16. block : pgm, exp or const
  17. fcn : a Mutt function (such as + or while) or defined function.
  18.  
  19. ======================================================================
  20.         Return Values
  21. ======================================================================
  22. All blocks return a value.  Pgms return the value of the last exp
  23.   executed. 
  24. The class of a return value can be one of:
  25.   BOOLEAN    TRUE or FALSE
  26.   BLOB        a pointer to a block of data
  27.   NUMBER    32 bit signed integer
  28.   STRING    a bunch of characters
  29.   VOID        a type of nothing
  30.  
  31. ======================================================================
  32.         Variables (aka vars)
  33. ======================================================================
  34. CREATION
  35.   Vars must be created (and allocated) before they can be used.
  36.   Global vars are initialized to:
  37.       bool: FALSE
  38.       INT, int, byte: 0
  39.       string: ""
  40.   Local vars are NOT initialized (ie they contain garbage when
  41.     created).
  42. EVALUATION & ASSIGNMENT
  43.   Vars behave like fcns, ie (var) evaluates the var (returns its value)
  44.     and (var val) passes val to the var for assignment.  (var val)
  45.     returns val.  If you just want to evaluate a var, you can treat it
  46.     like a const - ie var is equivalent to (var).  Note, however, doing
  47.     this may cause logic bugs if var also happens to be the name of a
  48.     const (since the const is locked out).  See GOTCHAS.  In some cases,
  49.     (var) and var don't mean the same thing - see pointer.
  50.   Cascading assignment:  you can assign multiple vars the same value.
  51.     eg (int x y z)(x (y (z 123))) assigns 123 to x, y and z.
  52.     eg (int x)(string s 20)(x (atoi (s "123"))) sets s to "123" and x
  53.       to 123.
  54. SCOPE
  55.   The scope of a variable is the same as the pgm it is allocated in.
  56.   A variable  allocated  outside of a fcn is global - ie anybody can get
  57.     at it.  Global  variables  are  local to the file (and any  included
  58.     file(s)) they are allocated in.
  59.   For example:
  60.     If foo.mut contains:
  61.       (int foo)        ; declare and allocate global var "foo"
  62.       (defun "hoho" {(int bar)(bar foo)})
  63.       (foo 123)        ; assign 123 to foo
  64.     (load "foo.mut") will create a global var foo.  (hoho)
  65.     creates bar and sets it to 123.  hoho is done and bar is deallocated.
  66.     foo remains allocated and equal to 123.
  67.  
  68. ======================================================================
  69.         Functions and Keywords
  70. ======================================================================
  71. Everything in this list is a function except those that have a return
  72.   class of zip.
  73.  
  74. KEYWORD [arg class(s) : return class] 
  75.  
  76. ; a comment that extends to the end of the line
  77. (== value value ...)    [STRINGs, NUMBERs or BOOLEANs : BOOLEAN]
  78.   Test 2 or more items for equality.  
  79.   You can only compare like types - eg (== "123" 123) is illegal.
  80.   eg (== foo 1), (== "one" "two"), (== (+ foo 3) bar 5).
  81. (!= value value)    Same as == but nonequality.  Only 2 items.
  82. (<  value value)    [NUMBER NUMBER : BOOLEAN]
  83. (<= value value)    [NUMBER NUMBER : BOOLEAN]
  84. (>  value value)    [NUMBER NUMBER : BOOLEAN]
  85. (>= value value)    [NUMBER NUMBER : BOOLEAN]
  86. (+ values)        [NUMBERs : NUMBER]
  87.   add a bunch of numbers  eg (+ 1 2 3 4) => 1+2+3+4
  88. (- values)    [NUMBERs : NUMBER]
  89.   subtract a bunch of numbers eg (- 1 2 3 4) => 1-2-3-4 = -8
  90. (* values)    multiply a bunch of numbers    [NUMBERs : NUMBER]
  91. (/ values)    divide a bunch of numbers    [NUMBERs : NUMBER]
  92. (+= var values)        [TOKEN, NUMBERs : NUMBER]
  93.   Add value(s) to var and assign it back to the var.  Returns the result.
  94.   Short hand for (var (+ var values)).
  95.   eg (+= foo 1) (+= foo fud 3) 
  96. (-= var values)        Subtract value from var. [TOKEN, NUMBERs : NUMBER]
  97. (*= var values)        Multiply var by value.    [TOKEN, NUMBERs : NUMBER]
  98. (/= var values)        Divide var by value.    [TOKEN, NUMBERs : NUMBER]
  99.  
  100. "string"
  101.   String constant.
  102.   Special characters:
  103.     \    quote the next character.  "\\" => '\'   "\^" => '^'
  104.     ^    convert the next character to a control character (make sure that
  105.       the letter is UPPERCASE!).  eg "^A"
  106.     Note: escape == ^[.
  107. 'string'
  108.   String constant.
  109.   No special characters except '' reduces to ' ie if you need a string
  110.     like "don't" use 'don''t'.
  111.   This form is handy for regular expressions.
  112.  
  113. (and values)            [BOOLEANs : BOOLEAN]
  114.   Logically and a bunch of things
  115.   The first FALSE value will terminate (ie the rest of the and will
  116.     not be evaluated).    eg (and (previous-line) (foo))
  117. (array type name dimensions)    [TOKEN TOKEN NUMBERs [TOKEN NUMBERs] : zip]
  118.   Create an array.  Types allowed: bool, int, INT, string.
  119.   (array int x 5 z 7) creates two arrays:  x with 5 ints and z with 7.
  120.   (array INT y 2 3) creates an array with 2 rows of 3 INTs each.
  121.   (array string s 5 80) creates 5 strings that can each hold up to 80
  122.     characters.
  123.   (x 3 123) sets the third element of x to 123.
  124.   (x 3) returns 123.
  125. (arg n)            [NUMBER : any class]
  126.   Get the nth argument from the parameter list.
  127.   The arguments are numbered 0,1...,(nargs)-1
  128.   eg (foo 1 "two" (three)) has 3 arguments:  numeric 1, string "two" and
  129.     whatever  fcn three  returns.  (arg 0)  returns  1, (arg 1)  returns
  130.     "two",  (arg 2) returns  result of  (three).  (arg 3), (arg -1), etc
  131.     error.
  132.   Notes:
  133.     You cannot set a arg unless it is a pointer.
  134.   See also: ask, defun, nargs.
  135. (ask prompt)        [STRING : STRING]
  136.   Get the next argument from the argument list; if the argument list is
  137.     empty, query the user.
  138.   eg if (foo (ask "foo = ")) is in fud then (fud "hoho") will pass "hoho"
  139.     to foo.  (fud) will cause the message "foo = " to appear and will wait
  140.     for a response to assign to foo.
  141.   You can force the pgm to query the user with (ask-user).  If you do
  142.     this, you will need one per ask.  The next unmodified ask will behave
  143.     as above.
  144.   See also: arg, ask-user, atoi.
  145. (ask-user)            [zip : VOID]
  146.   The next ask will query the keyboard and not the program args.
  147.   Turned off after every ask.
  148.   See also: ask.
  149. (atoi string)            [STRING : NUMBER]
  150.   Convert a string to a number.  If the string is not numeric,
  151.     atoi returns 0.
  152.   eg (foo (atoi (ask "A number please: ")))
  153.   Note: To convert a number into a string, use concat.
  154.     eg (string s 20)(s (concat 123)) will convert numeric 123 into a
  155.     string and assign it to s.
  156.   See also: ask.
  157.  
  158. (bool var [var ...])        [TOKENS : zip]
  159.   Evaluation & assignment: var, (var value) [TOKEN [BOOLEAN] : BOOLEAN]
  160.   Allocate 1 or more boolean variables.
  161.   Example: (bool foo)(foo TRUE)  ; set foo TRUE
  162.   See also: int, string.
  163. (break)                [zip : zip]
  164.   Get out of the smallest enclosing for or while loop.  The loop then
  165.     retuns the value of the last block executed.
  166.   See also: continue, for, while.
  167. (byte var [var ...])        [TOKENs : zip]
  168.   Evaluation & assignment: var, (var value) [TOKEN [NUMBER] : NUMBER]
  169.   Allocate 8 bit unsigned integers.
  170.   The range of a int is [0 : 255].
  171.   Note that a NUMBER may not fit in a byte.
  172.   See also: int, INT.
  173.  
  174. (case test body ...)
  175.   [[BOOLEAN, block, [BOOLEAN, block ...]] : last block executed]
  176.   Same as  nested  if's.  If the  test is TRUE  then the next  block  is
  177.     executed and the case is ended.  Otherwise the next block is skipped
  178.     and the cycle repeats.
  179.   eg
  180.   (string str 50)(str (ask "str = "))
  181.   (case
  182.     (== str "one")(msg "number 1")
  183.     (== str "foo")(msg "bar")
  184.     TRUE (msg str " is not something I know about.")
  185.   )
  186.   See also: switch
  187. (concat parameters)        [anything : STRING]
  188.   Concatenate parameters.
  189.   eg (concat "foo = " foo) return "foo = 123" if foo is 123 or "123".
  190. (const name value [name value ...])   [TOKEN BOOLEAN|NUMBER|STRING : zip]
  191.   Create one or more constants.  Used like other constants